I used to think documentation was just an optional ''docu-maybe-tion'', but boy was I wrong!😆 It turns out that skipping documentation can really c...
For further actions, you may consider blocking this person and/or reporting abuse
“ The documentation is not properly structured or easily accessible to all team members.”
I’ve seen so many docs that are either plagued with typos or so much tech jargon that it sounds like Navi(this the language of the blue characters in the movie Avatar). From what I’ve heard from other developers and technical writers, women are often assigned with this task, which is quite strange. Anyway, thanks for writing about this topic. I look forward to seeing more from you! :)
Haha, well said! This cracked me up.
And ughhh... you're absolutely right. It is so wrong to stick this task to women. I think it's really important that folks try to learn to document their own additions to the codebase. Can they have help? Of course, but the builder of the feature is closest to the task and should have a really good understanding of it... putting the work on somebody else just isn't as efficient as getting the person who built the feature to explain it. And hey, it benefits us all to practice our communication and documentation skills!
omg, its so true!
The jargons and the women being assigned to these tasks, you have summed it up quite nicely!
Thanks!
Completely agree. One of the forms of documentation that I usually do before starting new features is planning.
It’s very much like writing unit tests: by writing them, it makes us think in different ways that the system could operate. As a result, we might include additional handling for different use cases that we may not have otherwise thought of. The same is true with a project plan too.
When it comes to system design, I also think it’s helpful to draw up some diagrams. Architectural diagrams help with design and modularisation, and sequence diagrams can show how the systems will communicate with each other.
Once we have those, we have a clear direction and can generally move much faster as a result.
Totally Agree with that Anthony!
What tool/s do you use for system design btw?
To be honest, my initial approach for diagrams is usually quite low tech: pen and paper. I personally find there to be less cognitive overhead by creating diagrams by hand, even if it means I can't move the classes around after drawing them.
If it feels like something that I want to commit to, I'll either just take a photo or try to draw a neater version. Depending on audience, I might try to knock something up in a drawing package. I recently learned of Canva, and it certainly looks like it might make things a lot easier.
Are there any tools that you like to use?
Although I have less than two years of experience in software engineering, I typically use Draw.io to create initial sketches for my projects. However, I also use Camunda Modeler for BPM designs as per the business requirements.
Looks interesting - thanks for bringing those to my attention!
Literally EVERYONE in dev says this. All of the above, we all agree.
And NO ONE does it lol.
Many begin with good intentions and write some great docs...then by six months later the docs are completely irrelevant because no one took the time to keep up with the changes made to the application/site.
This happens to ALL documentation unless it's a very very very static system.
Have you ever used GitBook? I've used it a bit and feel that it's also a pretty good documentation tool. Much less customizable than something you totally selfhost but still pretty nice and you can update via WYSIWYG or raw markdown in GitHub.
great article, but you haven't mentioned the comments/documentation in the code. while not as important for a consumer, vitally important for developers.
If I don't do it, the first who is bitten is probably me coming back in a month or so and wondering what did I do and why...
Thanks for the feedback @webduvet 🙌, totally agree with the idea of adding comments explaining parts of the code, I actually try to practice this in real life, it was so obvious that I forgot to put that in 😅
It's certainly something to aspire to, but over almost 30 years in the industry (10+ companies from small startup to large corporation) has taught me that it rarely happens... anywhere. What usually happens is that there is a well intentioned effort to document things at the start of a project, but these documents are rarely updated and quickly get out of date to the point where they are all but useless. This then becomes a known fact about the documentation, and they are left to gather dust - usually only ever touched by new hires trying to find their way around an unfamiliar project.
The best way to even come close to solving this is to (largely) let your code be your documentation. You should aim to make it a 'living' document that tells its own story, and enforce a discipline of commenting anything whose purpose/implementation is unclear.
Great point! Rather than relying solely on documentation, using the code as its own documentation can be a smart and effective approach.
While it's important to document requirements and planning during the initial phase for newbies like me to understand the project better😅, adding comments within the code to explain specific features is also crucial.
Thank you, Jon, for sharing your valuable experience and insights!🙌
Counterpoint: If it took you a cycle to get your head around what the code does that probably is a massive time save over devs spending even 5% of each cycle documenting. And it avoids the most common trap of docs - outdated documents that give you a false confidence about what the code does.
Unit tests stay in sync, system tests stay in sync, good variable and method names stay in sync - anything that isn’t executable starts losing relevance and correctness the second you commit it.
Its when am getting used to it.
You got it! Thanks for your advises.