5 ms·

Ask HN: How do you manage disparate docs

1 points by dennisy 6y ago

I am interested in how people centralise (or do not) documentation from multiple git repos, into knowledge base. We have many small services each with a Readme, articles here and there etc. I feel I need to centralise them in some automated fashion to have a single place where people can find technical content both engineering and data science.

PaulHoule 6y ago
All in git with reasonable formats like markdown? Could you make something that indexes these in (say) Elasticsearch?
- dennisy 6y ago
  That seems unnecessary to push them into a DB - what is the benefit there?
  - PaulHoule 6y ago
    You can search the documents.
Juliate 6y ago
As time goes and if you ever grow, you will get more and more sources of info, on which you do not necessarily have control (from the extreme "it's managed by a vendor" or "it's public, useful reference info" to the other extreme "it's a new idea from the junior in the team"). What matters is indexing (for search) + cataloging (for structured discovery) the contents + managing access to it (because not everyone may be entitled to it, sometimes even not to its existence). You need a portal application/website that manages at least the 2 first, and always point your people to this portal first. It may be overkill when you're a small structure, but as you grow, and as you need to have processes for more and more things, this becomes a time- and org-saver. Because as you grow, and with time, you will inevitably face diverse teams having different preferences as to how manage/set/reform their own documentation. You don't want to block that, you want to keep track of it. Separating the index/catalog of the documentation from its various sources helps you keep track and manage on one hand, and helps your whole teams to keep information available to all.
- dennisy 6y ago
  This is a great point, we are just a team of 5 for now so this is not an issue, but out of interest how do you manage this - do you have a custom "portal"? What is relevant is that I am trying to achieve what you mention - I do not want to restrict and ask everyone to document in a single place rather centralise the access.

1 points by dennisy 6y ago

PaulHoule 6y ago

All in git with reasonable formats like markdown? Could you make something that indexes these in (say) Elasticsearch?

dennisy 6y ago
That seems unnecessary to push them into a DB - what is the benefit there?
- PaulHoule 6y ago
  You can search the documents.

Juliate 6y ago

As time goes and if you ever grow, you will get more and more sources of info, on which you do not necessarily have control (from the extreme "it's managed by a vendor" or "it's public, useful reference info" to the other extreme "it's a new idea from the junior in the team"). What matters is indexing (for search) + cataloging (for structured discovery) the contents + managing access to it (because not everyone may be entitled to it, sometimes even not to its existence). You need a portal application/website that manages at least the 2 first, and always point your people to this portal first. It may be overkill when you're a small structure, but as you grow, and as you need to have processes for more and more things, this becomes a time- and org-saver. Because as you grow, and with time, you will inevitably face diverse teams having different preferences as to how manage/set/reform their own documentation. You don't want to block that, you want to keep track of it. Separating the index/catalog of the documentation from its various sources helps you keep track and manage on one hand, and helps your whole teams to keep information available to all.

dennisy 6y ago
This is a great point, we are just a team of 5 for now so this is not an issue, but out of interest how do you manage this - do you have a custom "portal"? What is relevant is that I am trying to achieve what you mention - I do not want to restrict and ask everyone to document in a single place rather centralise the access.