The main focus for this month’s Melbourne Drupal Meetup was a presentation by Vladimir Roudakov. Vladimir took us through the state of Drupal documentation.
The state of Drupal documentation: presentation summary
This presentation introduced the topic of the state of Drupal documentation, emphasising it’s importance. Vladimir also shares his personal involvement with Drupal documentation as a teacher and Drupal contributor.
Current challenges in Drupal documentation
Vladimir highlighted several critical issues with the current state of Drupal documentation. He noted that the documentation is often inconsistent and outdated, which poses significant challenges for users, particularly new developers and those he teaches in private tutorials. Budget and time constraints frequently lead to documentation being neglected in software development projects, including Drupal.
Vladimir posed three rhetorical questions to the audience to illustrate the common issues with Drupal documentation:
- When was the last time you sent a link to Drupal ?
- Have you reviewed Drupal help recently, and if not, why?
- Have you updated Drupal help recently?
He pointed out that if users do not find the documentation useful or up-to-date, they are unlikely to recommend it to others or contribute to improving it.
Exploring Drupal help modules and examples
Vladimir explained the two primary help modules in Drupal: the help module and the help topics module. The help module allows for creating single help pages, while the help topics module can generate multi-page guides on specific topics. However, he noted that the help topics module had been moved to a core experimental module and labelled as deprecated, indicating it might soon be removed from the core system.
He provided an example of how the webform module effectively integrates help topics, guiding users through its functionalities. This contrasts with other modules, where help topics might be hidden or not readily accessible, creating a disconnect for new users.
Vladimir also compared Drupal’s documentation with GitLab’s, praising for its organised structure, versioning, and clear presentation. He suggested that Drupal could learn from GitLab’s approach to improve its documentation.
Common issues and proposed solutions
Vladimir identified several common issues in Drupal documentation:
- Poorly written content: Many documentation pages lack clarity, are poorly structured, and often lack visual aids like screenshots. This makes it difficult for users to follow instructions.
- Incorrect information: Some documentation contains outdated or incorrect information, which can mislead users. For example, certain guides incorrectly advise modifying core files, which is against best practices.
- Mixing guides for different user levels: Documentation often mixes instructions for non-coders and coders, which can confuse users who do not have coding knowledge.
To address these issues, Vladimir proposed several solutions:
- Regular reviews: Documentation should be reviewed and updated regularly. Pages that have not been updated in years should be flagged for review.
- Improving content quality: Contributors should ensure that documentation is clear, well-structured, and includes necessary visual aids. Feedback from users can be valuable in identifying areas that need improvement.
- Version information: Each documentation page should clearly indicate the Drupal version it applies to, similar to how GitLab handles versioning.
Contribution and the role of AI
Vladimir encouraged community involvement in improving Drupal documentation. He suggested joining contribution sprints and engaging with the documentation team on Slack. He also emphasised the importance of making small contributions, such as correcting typos or adding clarifying information.
Regarding the use of AI tools like ChatGPT for generating documentation, Vladimir expressed scepticism. While AI can assist with rewriting and making text more approachable, he noted that AI-generated content often lacks the precision and context needed for technical documentation. He highlighted that leading tech companies still rely on human-generated documentation, which underscores the current limitations of AI in this domain.
Conclusion
Vladimir concluded by stressing the importance of good documentation for the success of Drupal. He encouraged continuous improvement and community involvement to ensure that Drupal documentation remains useful and relevant. He also acknowledged the potential of AI to assist in the future but reiterated the need for careful review and human oversight to maintain quality.