Documentation day and guide #19
Conversation
|
|
||
| Keep in mind that your documentation does not have to be perfect. Your documentation has to be good or at least okay. It should be good to read. It may be fun to read. It never has to be wrong over a period of time. | ||
|
|
||
| **Focus on the content. _Always_.** |
There was a problem hiding this comment.
Documentation often tends to be either not enough or too lengthy to read. This is a good resource to get some advice on writing concise and useful documentation. I like the comparison with writing code: Keep it simple. Don't repeat yourself. Refactor ... https://developers.google.com/tech-writing
There was a problem hiding this comment.
So you suggest to add the link to the tech writing lessons from google, right? I think these will be a pretty good resource for extending the knowledge of technical writing.
We should keep in mind that the documentation guidelines, the one we discuss right now, have the purpose to make starting documentation easy as hell. First of all by keeping the Hemmschwelle as low as possible. I'm not sure if that is accomplished by telling the people: "Hey, documentation is easy and awesome! Start documenting where you are right now. By the way, here's a link how googlers do it. It's less than a day to complete. No pressure!"
I think you get the idea ;) Maybe that's a matter of wording:
| **Focus on the content. _Always_.** | |
| **Focus on the content. _Always_.** | |
| If you prefer to extend your knowledge in technical writing feel free to visit [the courses about technical writing provided by google.](https://developers.google.com/tech-writing) |
There was a problem hiding this comment.
I totally agree to making it easy. By pointing to this resource I didn't mean to suggest learning all things tech writing related, but rather providing some hints on how to write. I think often this is the main hurdle. Also, it gives some advice on what to look out for during the review. Maybe adding some examples of good and bad documentation is also a good idea, to make the topic more approachable.
| @@ -0,0 +1,29 @@ | |||
| # Documentation Day | |||
There was a problem hiding this comment.
Sounds like a whole day of reading documentation 😛 What about Documentation Review?
There was a problem hiding this comment.
Documentation Review sounds pretty good. Then we should think about to rename the Readme Day as well ;)
On the other hand "Documentation Day" and "Readme Day" sounds more like an "institution" than a (regular) task. The name should reflect the idea of the concept than what should be done.
There was a problem hiding this comment.
True, maybe I was biased in terms of selling this xD
Add documentation for a documentation day and documentation guidelines. Both should enable project teams to start making (technical) documentation a part of their engineering job.