The Problem with our Documentation
We have a problem with the majority of our documentation as Software Engineers: when we do decide to ...
For further actions, you may consider blocking this person and/or reporting abuse
Really like the Baseline idea, which could also answer the question "Who is this document for?"
The "Scope" looks like a Table of Contents, which a Wiki could autogenerate.
I would add that a "Takeaway"/TLDR section at the end of any document (what you did here!) is really beneficial.
Two very good points - you’re right in that a Wiki could auto generate the scope/table of contents, I just prefer to write it out myself ahead of time to give myself an idea on what I’ll be writing.
The takeaway idea is great! I’ve never thought of adding that to technical documentation - will have to experiment with that a bit more.
In the technical writing business, baseline is known as audience analysis.
Once one has settled on an audience, the next step is to determine the general contents of the docs. If the project output is a product, you'll need a basic outline like the following:
Despite the order of chapters, one typically starts with the lowest-level reference first.
Document all inputs, outputs, errors.
If one has time, create a simple example for every function.
And so on.
To really improve your documentation, hire a technical writer. But beware, you'll need to spend time bringing them up to speed, so don't wait until too late in the development cycle.
If the budget allows, also hire an editor (or contract editor if the project is short). The more eyes on docs, the better.
Thanks for sharing - as a Software Engineer I am far from a technical writer. I have never been fortunate enough to work with a team that hired a technical writer - us engineers have had to take it upon ourselves to write documentation and this is part of the method I've come up with when I go to write documentation. Having a dedicated technical writer sounds like a dream!
Very focused and on point. Any good literature you can suggest on documentation and concepts like these?
I have honestly struggled to find many good books on documentation from a Software Engineering perspective. There is a lot of literature and content out there around "Technical Writing" from a general perspective that you could look into. I personally have not read too much in this area since none of it seems applicable to my job as a Software Engineer.
That being said, here are two excellent books that look at writing documentation from more of a Software Engineers perspective:
I also plan to write a whole lot more on the topic, looking to publish a post weekly. So, you can also stay tuned for that!
Thanks for the two links I will definitely stay tuned as I currently see the benefits of documentation with onboarding my juniors
Google has a course about technical writing, it is a good starting point
developers.google.com/tech-writing
Helped me a lot! Thank you so much
Glad you enjoyed it!
I always found this talk very useful: youtube.com/watch?v=t4vKPhjcMZg
Also see: documentation.divio.com/