Programming

17313 readers

443 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Follow the programming.dev instance rules
Keep content related to programming in some way
If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities [email protected]

founded 1 year ago

MODERATORS

[email protected]

Software Engineering Documentation Best Practice? (self.programming)

submitted 1 month ago by Schal330 to c/[email protected]

34 comments fedilink hide all child comments

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?

you are viewing a single comment's thread
view the rest of the comments

[–] [email protected] -1 points 1 month ago (1 children)

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.

[–] [email protected] 2 points 1 month ago* (last edited 1 month ago)

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.