5mo ago

Software Engineering Documentation Best Practice?

Hey all, I'm still a junior dev with years of experience in IT. One of the things I've noticed since making the switch is that (at least where I work) documentation is inconsistent.

Things I encounter include incomplete documentation, outdated documentation and written process details that have assumed knowledge which makes it difficult for junior Devs to pick up.

I've had a search and a lot of what is out there talks more about product and how to document that SDLC rather than best practice in writing and organising documents against the actual software engineering and its processes.

Does anyone have any good sources or suggestions on how I could look to try and begin to improve documentation within my team?

34 comments

Be bold and make changes. Document what you find out, what is outdated, what is missing.
Take ownership. If there's nobody that oversees overall structure, be the one to do so - at least where you're touching it or are being bothered by it.
Diatraxis gives some great insight and considerations input into writing and structuring documentation. Namely how different target audiences and doc use cases require different forms and detail levels of guidance.
My company's internal doc/guidance also links to https://www.writethedocs.org/guide/ which seems like a good source.
- +1 for Diatraxis, my team has started using it to align all documentation.
- Sort of interesting that this documentation system appeared in two different places that don’t seem to reference each other.
  https://docs.divio.com/documentation-system/
  
  Looking at the Web Archive; Diatraxis has been around since 2021. That divio docs since May of this year.
  I doubt they didn't "get inspiration" from Diatraxis.
- Thank you for those links, it has given me a great place to get stuck into!

Bare minimum place to start: See if you can get the team to agree that these documents should exist in every project root folder:
README.md - What is this even for? Audience: Managers.
CONTRIBUTING.md - What steps are needed to build this? What steps are needed to be able to run the tests? Audience: Developers.
CHANGELOG.txt - Describes the contents of every tagged release. Audience: end users.
Stretch goal: pick a spot (readme is fine) and make a list of sources (data in) and sinks (data out). Include contact information for whoever can reset the credentials or fix the firewall.

I would say as a new junior dev you are uniquely placed to help with this. Documentation tends to be written by people who know a lot about a thing and they try to imagine what might be useful for someone. Someone new coming in with a fresh perspective can help uncover assumed knowledge or missing leaps to make the documentation better. One of the common onboarding steps I've seen is to go back and update/improve the onboarding docs after you've just been onboarded for example.
I would say pick your battles though because documentation can be a never ending task and documents are almost always out of date shortly after they are written. Think about what would have saved you time or mental overhead if it was just written down and fix those first.
As far as organising and writing, every place is different and it can depend on the tools your org is using. In general I'd at least have links to relevant docs as close to where they might be needed as possible. Like how to set up and get up and running with a code base should probably be documented directly in the readme, or at least linked to if it's overly complicated.
Hopefully that's at least somewhat helpful. It's definitely a problem basically everywhere I have worked though, you have to do what you can and not stress too much about it.
- Thanks for this. As part of onboarding I have been trying to update where I can. There are times I wonder if I am adding to docs what others may perceive as fluff as it may be something obvious to them. I like to work with a "If we're all on a bus that goes over a cliff, does someone new have everything they need?" mentality.
  At present the team is using GitHub Pages, which almost feels like a hurdle itself in updating the documentation quickly and keeping it organised and consistent. Being a junior I personally prefer a WYSIWYG. From your experience is there any pros/cons in using a WYSIWYG vs Markdown?
  
  No worries, sounds like you're definitely on the right track with your approach.
  In terms of the style of editor I don't have a strong preference, I think the most important thing is discoverability which generally means putting docs where they are expected to be found and using whatever your team or org is using. Personally I have a slight preference for markdown mainly because it's easy to version control, see who wrote what (so I can ask them questions) and use all the tools I'm used to that work well with plain text. Tools that use more WYSIWYG style can be good too though and many of them like Notion have the advantage of making it relatively easy to search across your entire companies documentation assuming everyone uses the one tool.
  For my personal notes I use Logseq which I highly recommend. It's a bit of both, markdown under the hood but with a simple editor that lets you focus on writing notes, tasks and links.

The Code is my Bible.
Things I encounter include incomplete documentation, outdated documentation and written process details that have assumed knowledge which makes it difficult for junior Devs to pick up.
Yeah seems about right... off the top of my head:
self-host a wiki, use it to document stuff
write clean code that your future self will have an easy time reading
avoid automated documenting tools
- Writings self documenting code is so important.
  Comments get stale and over time transition from: accurate to outdated, to eventually flat-out lies.
  Go hard in the paint when choosing method or variable names. If it's hard to give them coherent names, that's a code smell.
  
  Comments get stale and over time transition from: accurate to outdated, to eventually flat-out lies.
  Sounds like some people aren’t doing their work enough then. Code comments are part of the work that a programmer should do, not an afterthought. Who else is gonna update that code if not the programmer? And if a programmer isn’t supposed to update their code and we can just all write clean code that would somehow make us all be better engineers (yeah, I use this title differently from programmers), then why are code comments even a thing?
  Self-documenting code is good and all, but so should there be good comments.
- avoid automated documenting tools
  the output of tools like sphinx, javadoc and so forth is a good starting point, especially if you feed them properly commented code.
  the rule "garbage in, garbage out" definitely applirs here.
- If it's closed source then it's a losing battle to try and document code. I mean, do it when you feel it's 100% necessary (e.g. complex code that you really can't dumb down, "magic numbers" with a complicated backstory, test cases -- it feels like that's a different part of your brain so the transition is hard). Otherwise write code that almost reads like a sentence and don't add complexity until you need it.
  
  write code that almost reads like a sentence
  You mean COBOL?

Others may find this sacrilege but this is one the best uses for ai at the moment. I toss it methods and ask it to describe what’s happening each method. Then after you’ve gone through a whole class ask it to describe the whole class. If you break it up well it can very quickly document massive code sets specifically for both technical and non technical people. Even better it can take that same documentation and convert it to highly detailed and advanced markdowns for wikis. This will also help you review your code. If the ai is having an issues understanding what you’re doing you can bet anyone else dropping into it without backup is going to have issues too. Particularly PO’s, QA, Scrum masters and all those they meet with when you’re not there. It has saved me repeatedly showing up in meetings where those other non technicals just “ho hum” their way through meeting questions, come back asking where docs are because they usually don’t even bother looking. “No one else had anything documented and we didn’t see it so we just wondered.” “Yep here it is, here’s it broken down by class, here’s the method, here’s the variable types in and out, and here’s the quick overview levels 1,2,3,4 and 5.” All getting progressively more technical. My PO has thanked me repeatedly for saving her ass in meetings where they complain about lack of documentation but not from me.

Keep it all together with the code and use f.e. asciidoctor or rst ( python ). There is also doxygen but it's not most user friendly
- AsciiDoc ath Antora FTW!

Partial documentation combined with complex code will be great for your bank account.
Code fast, and badly, always under promise and over deliver. Before the shit hits the fan, move to another place.
Next person after you will take the blame. You may be hired again at premium as you can deliver. Blame the replacement Dev for breaking the code and causing a lot of damage.
Fix the little that is possible, at premium rate and move on.
- I'm still in those early cautiously optimistic stage where I hope I can make a positive change that will help those who come after me. How long does it take for the pessimism to set in? 😂
  
  Don't change. It's much more fun this way
  
  Be the change you want to see.
  And to answer your question, about as long as it takes to have 2 or 3 of people like them as your boss/lead.

This is the sort of thing you have to learn by experience, like how you can't really learn good coding taste from reading a list of rules (though some lists are helpful).
Anyway in my experience documentation is quite different in public (i.e. seen by customers) and private (inside your company). For internal stuff there's a much smaller incentive to document things because:
documentation tends to be inconsistent (as you discovered), so people give up looking for it. Instead they just ask other people. This actually works fairly well inside a company because you can generally easily access whoever is responsible (as long as they haven't left).
there aren't customers to keep happy and away from support.
I think the best thing to do is to accept that people aren't going to expect documentation internally. There's zero point writing guides to tools on your company wiki or whatever, because nobody will even try to look for it - they'll assume it doesn't exist.
Instead you should try to keep your documentation as close to the user as possible. That means, don't have a separate docs folder in your repo - put your docs as comments in the code.
Don't put deployment instructions on your wiki - add a ./deploy.sh script. It can just echo the instructions initially.

Does anyone have any good sources or suggestions on how I could look to try and begin to improve documentation within my team?
Documentation in software projecte, more often than not, is a huge waste of time and resources.
If you expect your docs to go too much into detail, they will quickly become obsolete and dissociated from the actual project. You will need to waste a lot of work keeping them in sync with the project, with little to no benefit at all.
If you expect your docs to stick with high-level descriptions and overviews, they quickly lose relevance and become useless after you onboard to a project.
If you expect your docs to document usecases, you're doing it wrong. That's the job of automated test suites.
The hard truth is that the only people who think they benefit from documentation are junior devs just starting out their career. Their need for docs is a proxy for the challenges they face reading the source code and understanding how the technology is being used and how things work and are expected to work. Once they go through onboarding, documentation quickly vanishes from their concerns.
Nowadays software is self-documenting with combination of three tools: the software projects themselves, version control systems, and ticketing systems. A PR shows you what code changes were involved in implementing a feature/fixing a bug, the commit logs touching some component tells you how that component can and does change, and ticketing shows you the motivation and the context for some changes. Automated test suites track the conditions the software must meet and which the development team feels must be ensured in order for the software to work. The higher you are in the testing pyramid, the closer you are to document usecases.
If you care about improving your team's ability to document their work, you focus on ticketing, commit etiquette, automated tests, and writing clean code.
- Hard disagree that documentation is a waste of time. I think you’re just failing to see and use documentation correctly.
  Tech documentation should never:
  record implementation details; that’s what commits and PRs are for
  be about the code, but about the solution, information, or provide guidance; use code comments when talking about code
  be taken as 100% accurate or infallible, but the general direction or essence should still remain true (related to the 2nd point)
  be expected to be up-to-date; readers should always look at the created / completed / last edited date and make a judgement how much salt to actually take from it
  Documentation can
  be some kind of paper trail that shows how we got to where we are
  provide guidelines for getting started on a project, or some part of a larger project, with more context with respect to the business, so that readers are equipped with sufficient context when diving into the code (READMEs can then just focus on setup and testing instructions)
  go further into what goes around a solution, eg considered alternatives, what actually requires solving given a functional requirement (it’s not always the case that we can fit a solution within a sufficiently small ticket, so tickets might be too localized to give a bigger picture of how a problem is being solved)
  record system architecture, with actual illustrations, which can be easier to grok than 50 Terraform files
  Writing these out is also good for people who don’t read code or don’t have the time to read code, eg your tech lead, your manager, Tech VP, etc, people who should have some idea of your system or solution, but not necessarily the implementation detail, so that they can do their work more effectively.
  There’s also a culture where a project, or a sufficiently complex problem, starts with a tech proposal, which would properly capture the problem and do solution planning. It’s easier and faster to change than a PR, and reviewers can read that for context. In any case, this democratizes knowledge, instead of creating more tribal knowledge.

Leave before it matters

Code should be self-documenting. That way it is never outdated. Here's an example of this similar to what you can expect to see in practice:

def nabla_descent(X, y, theta, alpha, delta, nabla): m = len(y) for _ in range(delta): h = X.dot(theta) nabla = (1/m) * X.T.dot(h - y) theta = theta - alpha * nabla return theta
- http://antirez.com/news/124
- Hilarious.

34 comments