To optimise and improve the process of collecting information about occurring issues, I propose a system for collecting and structuring information about them.
For each identified project-related problem, an information gathering thread (IGT) will be created. The main objective of the IGT is to collect data on specific project problems in an organised manner.
Each IGT will conform to a specific guidelines covering aspects ranging from the template format to the way data is collected and shared. The initial IGT post should contain a clear description of the problem, a complete list of possible symptoms (which may be supplemented in subsequent posts), a link to the relevant discussion thread, and a link to the rules. The thread title should summarise the nature of the problem, using the prefix “IGT” as an identifier, for example “IGT: Description”.
In addition to IGT, an auxiliary topic with an identical title but without the prefix will be created. This auxiliary topic is intended to facilitate in-depth discussion of the problem. While the IGT is strictly intended to convey factual and concise information, this ancillary topic facilitates a more interactive dialogue about the issue.
Each IGT will be tagged with the appropriate descriptors according to the guidelines to ensure efficient indexing of issues. Within an IGT, each contribution is categorised. These categories include:
- Templates for collecting valuable data.
- Templates for collecting case information.
- Valuable data (e.g., similar issues in other projects).
- Case study information.
- Assumptions or suggestions.
- Possible solutions.
- Confirmed solutions.
- Feedback on proposed solutions.
- Updates to the issue (e.g., new symptoms).
- Those that do not fit into predefined categories.
To maintain consistency, each entry in a category should be sequentially numbered.In addition, it is essential that each entry has a standardised format to ensure that the content conforms to accepted English language norms.
A generic template will be used to document node-related problems, in case a specialised template has not yet been provided. This template will include the following information: operating system used, installation method (Pulsar or Advanced CLI), version/release used, node parameters, farmer parameters (if Advanced CLI is used), node and farmer logs, installation specifics, and additional notes. All logs should preferably be presented in text form, enclosed in code blocks, and placed in labelled spoilers. Images should also be hidden under labelled spoilers.
Although any user will be allowed to create IGT posts, the moderators reserve the right to delete them or require modifications if they do not conform to the established rules. To avoid such inconsistencies, participants are advised to discuss them with colleagues before creating a new IGT. Duplicate IGTs dealing with identical issues will either be merged with an existing topic or deleted entirely. For generic threads on these issues, the initial step is to consolidate relevant data within that thread and subsequently redirect it to the corresponding IGT thread.
The solution to the issue will only be confirmed after verification by an authorised body (e.g. developers). It is very important that templates are created by people who are familiar with the data that can shed light on the nature of the problem. For significant files such as logs, external hosting is recommended, and compression is recommended where appropriate.
To ensure that the templates within IGTs are effectively designed to gather all pertinent information regarding an issue, a structured approach to creating these templates is vital. This involves specifying each data field along with a concise instruction on how to retrieve the required information for that field.
Outlined as:
Field: Method to obtain the data for said field.
Illustrated with the example:
CPU model: On Linux, this can be procured using the command lscpu | grep -i "model name"
By implementing this rule for template creation, it guarantees that users, even those less experienced, can effortlessly and accurately provide the necessary data. This will significantly enhance the precision and consistency of information gathered in IGTs, thus expediting problem resolution.
In conclusion, the presented system, while offering a structured approach to finding solutions and collecting information about the issues, undoubtedly requires further improvement and refinement. I believe that collective wisdom can enhance this proposition immensely. Thus, I would be genuinely appreciative of any feedback or suggestions that can help shape this into a more robust and effective system. Your insights are invaluable.