今日推荐开源项目：《0费 Linux 牌 super-inspire-end》
今日推荐英文原文：《How I document — 7 tips for starting, writing and maintaining your documentation》
今日推荐开源项目：《0费 Linux 牌 super-inspire-end》传送门：GitHub链接
推荐理由：让你得到一个简单快速的临时 Linux 系统，只需要一些基础的设置就能开箱即用。这个项目可以让你通过 web 临时使用一个干净的 Linux 系统，在你刚好暂时需要它们的时候相当管用——比如尝试 GitHub 上的项目或者为帮助暂时没装 Linux 系统的同学，当然它还有更多方便的用处，可使用的系统种类之后也会增加，如果期待后续发展的话不妨关注一下。
今日推荐英文原文：《How I document — 7 tips for starting, writing and maintaining your documentation》作者：Curtis Stanier
原文链接：https://medium.com/@crstanier/how-i-document-7-tips-for-starting-writing-and-maintaining-your-documentation-6e858af64c0
推荐理由：写好文档的 7 个小技巧
How I document — 7 tips for starting, writing and maintaining your documentation
ocumentation is one of those topics that elicits a groan whenever it’s mentioned. We all know we need to do it, we all know we should do it, and we will get around it — after we’ve finished this task, or tomorrow, probably.Documentation is the thing that we will do eventually. But many teams are wasting time and focus by delaying it. Ask yourself how many times you’ve answered the same question via Slack? the ticket that was delayed because we had to wait for someone to get back from vacation? Or that service that went down in the middle of the night and no-one knew how to starting fixing it? How much time was lost through all those occurrences and think through how many times a week, month, year that is happening in your organisation.
Patrick Kua touched on the topic of documentation in one of his talks and he phrased it wonderfully:
Although, the agile manefesto preaches “Working software over comprehensivedocumentation” — it doesn’t preach it over no documentation.
Far too many organisations and teams continue to function through tribal knowledge. Tribal knowledget is unwritten information not widely known by many others and results in a slow pace delivery and a lower quality of product. Good documentation is not a silver bullet to all your problems but it is an underutilised building block to get there.
Documentation can be anything; API contracts, Initiative Requirements, Business Cases or Meeting Minutes — anything that has value or meaning to others inside (or outside the organsiation).
Documentation is one of those topics that elicits a groan precisely because we feel guilty for not doing it sooner. We feel guilty because we’re very aware that everything I’ve mentioned above is true. Often, the task seems overwhelming but it doesn’t have to be painful to acomplish. In this article I share 7 tips for producing more useful documentation, faster, and embedding it into your working routine.
1. Just start —I promise this is not an easy-out answer to open the list, I mean it. Starting can be as simple as creating a new page with the title — this is the most basic building block you need. The simple act of creating a starting point can be enough for you to start filling in basic details you need to get down. The file is already open, it’s no huge step to contribute something now. Your first small win can lead you on to another — giving you a feeling of acomplishment.
2. Start simple — people are often daunted by the scope of what needs to be produced. Documentation can be extensive with introductions, glossaries, detailed descriptions, diagrams and references. However, it doesn’t all have to be there from the start. One of the many mistakes people make is feeling they have to produce everything in one go. When we build products we aim to start with an MVP — the same should be done for documentation.
Someone needs to get from A to B. The first iteration isn’t perfect but it’s better than walking… Credit — Henrik Kniberg
Most Product Managers are now familiar with the above. It was produced by Henrik Kniberg in an attempt to explain what an MVP should actually be. A summary of the topic at hand is a good starting point — throw in a few links to other important resources (screenshots, designs) and you’ve got yourselve the basics of documentation. It may just be a skateboard — but it will get them on their way.
3. Update when someone asks you a question — this is probably my biggest piece of advice on the topic of documentation. Its requires a bit more discipline but I found it dramatically improved the quality documentation I was writing and made my life easier. I discovered this tip quite by accident. One day, I was in the process of updating a page when I was asked a question by a colleague. The question was a good one and the answer wasn’t documented anywhere. Incidentally, the page I was working was actually the best place for it so I quickly added a section and sent them a link. Unrelated, a few days later someone asked me a very similar question and instead of rewriting my answer I sent them the same link again. It was that moment that I realised if someone has a question — it is likely someone else with have it too. Updating content in response to questions has additional benefits — you’re getting direct feedback from the audience on what they need so you can tailor it. Once people know where to find your (awesome) documentation, they will likely share the links and even reference it before asking you. Double win!
4. Ask others to contribute — as the old saying goes, many hands make light work. You should not be expected to soley product every piece of documentation. Save in one-person operations, you’re going to be working in a team and there everyone has something to contribute. If there is a topic that needs adding but you don’t have the detail, ask one of your colleagues to add a paragraph or two of their expertise. I can assure you, they will likely do a better job because the content is being produced by the person that truly understands it. Similarly, if someone lets you know something is out of date — kindly ask them to amend the document with the right information. The majority of our documentation should be a living — you’re not the only life-support machine around.
5. Let it grow organically — this really is the outcome of the three pieces of advice above. If something needs adding, priortise adding that now — otherwise, keep coming back and contributing as things occur to you and when you find time. Updating documentation should not be a laborious, several-hour task but something you can do in small chunks of time. For example, If I have a meeting finish early I will try to use that to quickly update any docs that were affected by it. This approach means you’re constantly breaking down the task into easy and manageable chunks around your existing workflows. My only exception to this method is if I am producing a diagram or drawings. These are more involved and require a higher time investment but dramatically improve the effectiveness of the document. Be sure to carve out some time for them. This leads us nicely onto Tip #6…
6. Apply formatting — this becomes even more important as a document or page gets larger. A wall of text is difficult to scan for relevant information and simply result in people asking you directly (Again). We’re not writing Shakespear — your job is to be as efficient and effective at communication information as possible. You have a vast array of communication tools at your disposal beyond prose so be sure to use them:
- Sections & Headings — make the most of nesting content in a structure way. Add a Table of Contents to the start of the document (most tools allow you to generate these on the fly). It makes it really quick for someone to jump to the relevant section and discover their answer
- Images — a picture is worth a 1,000 words. Particularly when referencing designs or flows benefits the reader to see what you’re referencing
- Process diagrams are an excellent way at helping others understand a flow or decision tree in a way that paragraphs of text will not. Don’t forget to include a key and a clear scope so your reader knows that the diagram does or does not cover.
- Tables are perfect for displaying structured data. I often use them to support lists with multiple dimensions (e.g. outlining the project team — name, role, contact details and responsibilities).
So that’s it, the 7 simple tips I us to improve the coverage and quality of the documentation for the Products I own. Since I started with this method, I have over 50 pages authored and more than300 edits on our team’s confluence space alone. But those aren’t the metrics that really matter. The real measure of success is the increasing numbers of people referencing our team’s documentation, fewer people asking us the same questions and most satisfyingly of all — individuals reaching out thanking us for the helpfulness of our docs.
下载开源日报APP：https://opensourcedaily.org/2579/
加入我们：https://opensourcedaily.org/about/join/
关注我们：https://opensourcedaily.org/about/love/