Has any founder of a small/medium team felt that their documentation tool is lacking?
I'm currently developing a new documentation tool called Scribe that is focused on teams. In my previous software role I found our team wiki (Confluence) to be a black hole. We had little to no visibility into how others interacted with our content, search did nothing for helping you find unknown unknowns and acting on outdated documentation became a common occurrence.
I recently had an epiphany that I was solving my problem, however I wasn't really focused on the needs of the stakeholder that could authorise the purchase. I'd be really interested to hear from anyone, but in particular founders, about your experience with your documentation tool (e.g. Confluence, Slab, Notion, Dropbox paper, ect). Is there anything that I could offer that would make you willing to throw money at me?
I do a lot of work with hundreds of software teams across several Enterprise customers. At least for them, this is not a tooling problem...it's a culture problem. You can swap in different documentation tools all day, but the tools won't be responsible for the behavior change that needs to happen to make the tool viable.
For this product, I worry that you're building gloves for a naked person in Antarctica. The person is naked by choice and the gloves won't make them warm, even though being warm would be beneficial.
This good Sir is a great response, it has given me a lot to think about.
I agree with you that it can be a culture problem, but cultural problems usually arise when incentives don't align, and misaligned incentives are something a tool can attempt to fix.
I think it's a safe assumption to say most people can see the value a thorough up to date wiki can provide. If this is the case then the only reason most wikis become black holes is really because employees aren't rewarded for doing a good job of it (or worse yet they are punished for spending their time on "non-critical work"). People signed up for Confluence and create documentation because there is value for everyone involved, they want to share knowledge and not answer the same question 100 times. Then the question becomes why do these tools still suck, why aren't incentives aligned to make thorough up to date wikis a reality?
One reason might be that managers can't quantify how useful their knowledge base is, or how much time people spend on it (which in my experience is quite a bit). A possible solution to this is to provide managers with wiki-wide analytics so they could quantify it's usefulness. You could also offer a more prominent feedback system (e.g. a clap button like Medium has) to hammer home the value people were deriving from the wiki. I could still be a bit off base with this reasoning but I would be surprised if the problem was not a fixable one.
In your experience were the people in those teams making a solid effort to write something, but having the incentive structure work against them (i.e. no time to write thorough documentation or go back and update outdated documentation)? I'm really keen to hear your opinion on why the culture problem exists, and if it's more the fault of one party than another.
Part of me just refuses to believe I can't sell clothes to all those naked people in Antartica.
To summarise I think that there has to be something here because:
It was actually the opposite. The team members didn’t want to spend time writing documentation, because there were far more effective ways of knowledge transfer. Senior management bought the tool, not the developers.
Senior management thinks documentation in a tool is important, so they buy a tool. Developers have better ways of knowledge transfer that are less time consuming and more collaborative, so they don’t use the tool. Senior management sees the tool isn’t used, they assume it’s because the tool is bad, so they buy a different one when the three year contract is over.
In these teams, many of which are extremely high performing, they share knowledge through well written user stories, well written tests, weekly office hours, and pairing. They go straight to the source, rather than read a page, have questions, make a comment, wait for a response, ask a follow up, etc.
Very interesting... this is quite different from my experience.
In regards to user stories, I found while they were extremely useful in explaining why a particular task was created, they were often placed in Jira tickets which become really hard to track down after some time has passed. Also a larger task could be scattered over many Jira stories which only made this more confusing. Plus the quality of user stories unfortunately varied greatly.
Tests really only help you understand how the code functions, but don't help you understand why it was written that way in the first place. Also they are obviously purely for understanding code whereas a wiki contains everything from admin and HR related info to retro notes, runbooks, ect.
And pairing, while fantastic for quick knowledge transfer
The bulk of what would be repeated in these sessions should have been written down. Getting someone to study that content and then come with targeted questions saved the pairee a large amount of time and was just as effective in achieving knowledge transfer.
I'm not really sure what you mean by weekly office hours, what were they?
I believe the reason team members didn't want to spend time writing documentation is to do with all the problems my product is trying to solve. They saw it as a waste of time because without those issues addressed it largely was.
Maybe allowing for a Q&A to take place in the wiki tool could be useful? This could be in the form of a chat or maybe even a video and could be used to document fast changing content. You could then pair a document with a Q&A to solidify the learnings in a well thought out way, when the content was no longer changing day by day.
I’d encourage you to continue doing user research. I’m obviously only one person sharing my experiences, so there’s not really much sense in us going back and forth on how our experiences differ. The reality is the teams I work with are likely likely your target audience, and that’s ok!
Find those that are and get as much info as possible from them. Good luck!
Not necessarily the feedback you're looking for, but I'm also working on a technical product documentation tool with respect to database documentation. The particular issue that I'm working to solve has to do with documenting project databases in a way allows project teams to author documentation for specific audiences and facilitates maintenance of this documentation as the project changes over time.
Nice to know someone here is working in the same space. How far along are you? Have you managed to get any customers on board? Also what differentiates it from a more general purpose documentation tool?
Also just interested to know, have you ever had any of the issues I described with confluence/whichever tool your team used?
That particular project is still in the ideation phase while I finish the v1.0 of another project, practiceSQL.com. I've used or built most of the tech that I plan to incorporate in other projects so I don't expect the initial build-out to be too complex. I've spoken to a few potential customers and will continue these conversations as I get further along.
The differentiator is the niche; I'm only planning on developing tooling that allows project teams to produce maintainable database documentation. The existing solutions are too cumbersome, special-purpose, limited, or targeted at the wrong audiences. For example: a DBA can use enterprise architect or something similar to produce attractive ERDs but that won't help an analyst or tester understand the "why". Most of the manual mechanisms for maintaining database documentation are out of date the instant they are written, especially for an active project.
The secret sauce is the ability to version the documentation, to detect schema changes and update the spec accordingly, and to export it to multiple formats on demand. In this way, the tool I'm building can be one key part of a more comprehensive project documentation strategy :)
This makes sense, I've definitely looked at db specs and wondered why they made it that way many a time, plus I've read outdated schema documentation just as many times. The ability to tie a document to a snapshot of the spec would be quite useful, sounds like it's in the vaguely similar vein to my products ability to have if-this-then-that abilities, i.e. if this schema is updated then mark this document as outdated.
Would you go the route of having a tool like dbdiagram.io that can actually make the diagrams as well? Seems like having a documentation tool and a DB design tool as seperate entities will always be a little cumbersome.
I've never been a huge fan of entity diagrams; it typically seems like I have to resort to using them when the database structure or standards (e.g.: table/column names) are poorly implemented. Other times, the structure is so complex that the entity diagram is so physically large as to be nearly useless to visualize relationships. Given that there are already tools to create such diagrams, I see no need to reinvent that portion.
The way that I see this project progress is to create the tools that facilitate the production of narrative documentation and work with users to refine the output to meet their needs. I know what I want and intend to build that first.
Since I haven't asked- how far are you on your documentation projects?
Interesting, I found them useful when creating the design initially and for grokking it quickly later on, but I can't say I've ever worked on anything super complex. I do see your point that that's not really a value add when it's already done by others pretty well.
Right now I have the designs more or less done both for the UI and DB. I spent too much time on the UI side of things though, I even have a really fleshed out styleguide and symbol system in Sketch to make iterating really quick, but it really wasn't necessary this early on.
I've also started building out the backend using Elixir and GraphQL. I hadn't used either of these before which wasn't a smart move when it came to speed, took me quite a while to become sufficient enough. So far I've implemented a login system, that again was too well thought out this early on.
My hope was to implement a fully functioning GraphQL endpoint first and then use NextJs to build the front end (I need the Server Side Rendering because I plan to allow for public documentation that can be indexed by Google).
However I've put the breaks on the engineering side of things at the moment to try and talk to as many people as possible in order to refine the vision. I don't want to build anything else until I can find at least one customer that needs it. To that end I've arranged meetings with my former boss and a few managers (that's happening tomorrow) to try and sell them on it/get their opinion. I know their teams had the problems I'm trying to solve so if they aren't interested it might mean I need to pivot the idea to target a demographic that desperately needs what I'm selling. Other than that my goal is to send a few hundred cold emails (experimenting with the subject line and body every 10 or so) to try and get my first customer.
That sounds like good progress! I'd be curious to hear about your experience with GraphQL.
If you wanted to share any early prototypes, let me know. I lead a few development teams in addition to hands-on app development so I suspect that I'd be in your target demographic even if it's unlikely I could make use of such a product (as my 9-5 is within a fairly large enterprise with its own set of tools).
Thanks :) I'm still very early days with GraphQL but so far I have found it to be really interesting. When working at my previous role I found Rest APIs to become bloated incredibly quickly, and observability regarding what Rest endpoints already existed was really poor leading to a lot of duplicated effort.
GraphQL seems to require a little bit more thought up front regarding how to structure your schema, but it's definitely worth doing. Plus GraphiQL (in browser editor for exploring your GraphQL endpoint) is AMAZING.
My pain point so far has really been around implementing login with GraphQL, and the fact that GraphQL in theory does not require HTTP so libraries like Absinthe (toolkit for building GraphQL APIs with Elixir) add layers of indirection that can be really confusing.
Implementing login within GraphQL requires you to accept unauthenticated requests and in my implementation modify cookies (for the session and refresh tokens). However because GraphQL doesn't require HTTP, Absinthe doesn't give you direct access to the connections cookies, which means you need strange workarounds. After posting on the Elixir forum (https://elixirforum.com/t/why-doesnt-absinthe-expose-plug-conn/25752) I found out that most people just implement login outside GraphQL to get around this. This might just be an Elixir issue though.
I've also heard that things like rate limiting and caching can become quite a pain with GraphQL, but I'm not currently far enough along to worry about it. When I'm further along I'll most likely post my learnings up somewhere :)
As for the early prototypes I will definitely take you up on that offer! I think you are smack bang in my target demographic so I would love to get your feedback along the way. Would also be really keen to know what I would have to do to build into Scribe to get your work to sign up as a customer (assuming you/they liked Scribe of course). Are they currently using Confluence or their own proprietary tool?