For internal software product documentation, what are your parent pages and what do they include?

Question

I am rebuilding our product internal documentation where the Technical Requirement Documents, Meeting Notes, and other things.

I am looking for a way on how to organize the documents and future documents in the new product space.

Need your suggestions :)

Thank you!

Victor - New Verve Consulting · Answer

Hi @Kyren Cabellon

Some amazing answers here! My 2 cents of how our product spaces are organised:

* Requirements - product owner fills in what the product should do
* Analysis - feature feasibility and technical specifications from developer team
* Documentation - technical documentation of implementation
* Marketing - marketing content (images and text copies)
* Meetings
* Project Management - sprint planning pages and reports
* Testing - test plan and test notes from testers
* Release Management - document versions and feedback to complete the loop

Hope this helps!

Victor

Robert Reiner _smartics_ · Answer

Hi @Kyren Cabellon

I assume that your question regards the role of parent pages as a means of organizing a space for products. The organization of a space does heavily rely on the expectations of your users (including roles that create the content and roles that use the content) and your requirements (what information do you want to provide in which environment etc.). Since the information architecture of your space is an answer to your requirements, it is quite difficult to have a generic answer here that goes beyond some suggestions like "Did you think of ...?".

So here some abstract guidelines that we are using when organizing a space in Confluence.

You may want to have your documents separated from your records. Documents that for instance specifies how you work and maybe requires versioning have other maintenance efforts as records (e.g. meeting minutes) that are created at one time and never changed again (see Frequency of Change). We have separate spaces (may or may not map to Confluence spaces) for this:

* product information for the user of the product,
* system information for the team that creates the product,
* process information that defines how the team works together and with other stakeholders, and
* project information that documents what has been done (typically records).

In our design we often use repositories for a type of documents (or records). Each document has properties and we provide a couple of views on these documents (per automatic lists or transclusions aka excerpts in Confluence terms): services, systems, roles, stakeholders, guidelines, tools (user manuals best practices), etc.

It is from the view of an author: "Where should I place this piece of information?". The answer may be the repository (because it is a new requirement) or the child of an existing requirement (because it is a sub requirement). The practices that are involved here are Physical Location and Welded Lifespan (at least this is how we name them).

For Physical Location the parent page collects all pages according to an invariant of the document (repository). This is relevant because you do not want to change the location of the document because one if its variant properties (for instance labels) changes.

The Welded Lifespan selects a page to be a parent of other pages, because all child pages should be removed in case the parent page is removed.

I am not sure if your question for parent pages is less a functional one, but semantic: What type of documents do I need for a product documentation. Here it would be easier to list, what you already have so that the community could suggest additional document types that have been relevant to them in the past. But as I said, this relies on the requirements and your audience / team.

Hope this helps.
Cheers,
Robert

Kyren Cabellon · Answer

Hi @Nicolas Gondard , I'm looking more into what parent pages are usually in your product internal documentation spaces - e.g. Technical Requirement Documents, Meetings, etc.