[Task] Cross-projects contributor exp: Evaluate the project_template's docsite template with an eye toward personas

ansible-community / community-team

For issues to be done by the Community Team that don't fall into a particular repository

0 stars 2 forks source link

[Task] Cross-projects contributor exp: Evaluate the project_template's docsite template with an eye toward personas #537

Closed Andersson007 closed 4 months ago

Andersson007 commented 5 months ago

Task of epic https://github.com/ansible-community/community-team/issues/416

Evaluate the project_template's docsite template with an eye toward personas

https://github.com/ansible-community/project-template/pull/8#issuecomment-2093050846
Ansible docsite landing page based on personas: please take into account that Ansible is special in terms of its size, complexity, components, age, etc., so I wouldn't be in favor of using it as a universal template for ecosystem project
Epic https://issues.redhat.com/browse/AAP-23304

Jira task https://issues.redhat.com/browse/AAP-23721

oraNod commented 4 months ago

@Andersson007 and @samccann I've sent a PR to improve the template from the novice perspective. I think what is in the template addresses the other personas well enough - although maybe we should have some detail for developers. Would it make sense to add a "developer guide" template?

oraNod commented 4 months ago

I think the developer persona is covered with the CLI and Porting Guide templates in the doc references. However it might be good to consider test coverage and API access/reference.

oraNod commented 4 months ago

For the other personas, I think the user is covered with the installing and how to template. There is plenty of info for the community maintainer persona in the maintainer guide. For the community member/evangelist persona, it seems like the contributor guide template has all the detail on non-code contributions.

Andersson007 commented 4 months ago

@oraNod

Would it make sense to add a "developer guide" template?

it's a part of contributor guide now https://github.com/ansible-community/project-template/blob/main/docs/contributor_guide.md , the idea is that for the majority of the projects having it separate would probably be an overkill considering their size. There's also a note in that guide saying "Consider having a separate code contributor guide and a link to it from here." In that case, it should inherit the section structure to elaborate on the subsections in detail in the separate doc.

oraNod commented 4 months ago

Thanks @Andersson007 - Not sure why I didn't think of that part of the contributor guide as I did look at it. I think I just get fixated on ideas or questions. Anyway I suppose we're covered with the developer persona given (so cheers!).

samccann commented 4 months ago

I think the developer persona is covered with the CLI and Porting Guide templates in the doc references. However it might be good to consider test coverage and API access/reference.

Can you create a separate issue for that if needed? Going to close out this issue as done. Thanks!