6 ms·
First off when you say: > My team currently has very few docs for their codebases Note this is the default state in most companies and organizations, so don't
by ivan_ah 6y ago
First off when you say:
> My team currently has very few docs for their codebases
Note this is the default state in most companies and organizations, so don't feel you have an especially bad deal.
> [...] but I've never really learned or put in the effort to WRITE good documentation myself.
There are no special skills required to WRITE docs, other than to simulate what info the ppl who will READ the docs might need. So in a way, your past experience reading good docs optimally prepared you to write docs now.
Overall I think you have an interesting opportunity to add docs to various projects you will be involved in (very worthwhile experience to write things up to understand, and help future onboarding of collegues, but also to help with extraction and exchange of info within existing team.
My recommendations would be to start in the following order:
1. README.md in each repo with ##Installing and ##Running sections (avg. dev setup should not require a meeting or support—REDME should be self sufficient)
2. Data models info (since code bases can be 100k+ lines of code and you have NO chance of understanding right away, you can start by looking the DB tables. Ideally export the schema from a production DB so have latest info. Look for tools to help you extract info and transfer to a shared spreadsheet where can be further annotated.
3. API endpoints. You don't need to document everything, but if you can get a list of all endpoints for a service it can be very helpful (`./manage.py show_urls` in Django if you have django-extensions installed).
4. System diagrams. This is not really for you as a beginner to do, but maybe you can ask some of the more expreinced teammates to draw an overview diagram of services and interactions (think box-levle diagrams like business people would use in slides, not detailed). You can volunteer to turn hand-drawn summaries into nice diagrams to use in docs (this kind of birds-eye overview diagrams are very useful for beginners, and generally low maintenance since don't have details).