update to documentation, use of wiki


J Lovejoy
 

Hi folks,

I made some updates to some of the documentation files in the Github repo today related to some conversation on the call. Would love to have some feedback. See: https://github.com/spdx/license-list-XML/pulls
(981, 982, 983, 984)

This led me to realize we still refer to the wiki as our working area (and it’s the only place - I think - we have the info about the bi-weekly calls, which is now outdated!) https://wiki.spdx.org/view/Legal_Team

While I have no appetite to shut down the wiki and there are some good resources there, what are thoughts about perhaps redefining how we use it? Off top of head:
- for meeting minutes
- recording old decisions (existing, but this could mean we could still opt to record stuff there in the future if it’s deemed the best place?)
- proposals we are hashing out, but aren’t appropriate for a Github issue

In the spirit of having only one place to update - I’m thinking we might move the call info to the Github readme and remove from the wiki page?? more likely to be seen there.

Thoughts? ideas??

Thanks,
Jilayne


William Bartholomew
 

While I am biased, GitHub issues are pretty useful and some of these scenarios are pretty well handled with issues and it gives people one place to look for content. For example, we could create an spdx-meetings repository, create an issue to capture the notes from each meeting (you can use markdown, embed images, links, etc.), use labels to categorize as legal, tech, or general to enable people to filter. Since people can comment on issues they can leave comments to "approve the minutes", ask questions, or provide feedback.

Issues can be used for proposals but if the proposal is content heavy and needs to iterate a lot then I find pull requests are better for this.

If we'd like to pursue these options I'd be happy to create the repositories, template issues, and write up a bit of a user's guide for people that are less familiar with GitHub.

William

On 2/27/20 12:53 PM, J Lovejoy wrote:
Hi folks,

I made some updates to some of the documentation files in the Github repo today related to some conversation on the call. Would love to have some feedback. See: https://github.com/spdx/license-list-XML/pulls
(981, 982, 983, 984)

This led me to realize we still refer to the wiki as our working area (and it’s the only place - I think - we have the info about the bi-weekly calls, which is now outdated!) https://wiki.spdx.org/view/Legal_Team

While I have no appetite to shut down the wiki and there are some good resources there, what are thoughts about perhaps redefining how we use it? Off top of head:
- for meeting minutes
- recording old decisions (existing, but this could mean we could still opt to record stuff there in the future if it’s deemed the best place?)
- proposals we are hashing out, but aren’t appropriate for a Github issue

In the spirit of having only one place to update - I’m thinking we might move the call info to the Github readme and remove from the wiki page?? more likely to be seen there.

Thoughts? ideas??

Thanks,
Jilayne






Alan Tse
 

Also, GitHub does have built in wiki functionality not to mention multiple ways to generate websites/documentation using the repo functionality. I don't think issues are the best way to capture meeting minutes, but using the existing GitHub functionality does allow for easy cross referencing between issues and other items.

On 2/27/20, 3:39 PM, "Spdx-legal@... on behalf of William Bartholomew" <Spdx-legal@... on behalf of iamwillbar@...> wrote:

CAUTION: This email originated from outside of Western Digital. Do not click on links or open attachments unless you recognize the sender and know that the content is safe.


While I am biased, GitHub issues are pretty useful and some of these
scenarios are pretty well handled with issues and it gives people one
place to look for content. For example, we could create an spdx-meetings
repository, create an issue to capture the notes from each meeting (you
can use markdown, embed images, links, etc.), use labels to categorize
as legal, tech, or general to enable people to filter. Since people can
comment on issues they can leave comments to "approve the minutes", ask
questions, or provide feedback.

Issues can be used for proposals but if the proposal is content heavy
and needs to iterate a lot then I find pull requests are better for this.

If we'd like to pursue these options I'd be happy to create the
repositories, template issues, and write up a bit of a user's guide for
people that are less familiar with GitHub.

William

On 2/27/20 12:53 PM, J Lovejoy wrote:
> Hi folks,
>
> I made some updates to some of the documentation files in the Github repo today related to some conversation on the call. Would love to have some feedback. See: https://github.com/spdx/license-list-XML/pulls
> (981, 982, 983, 984)
>
> This led me to realize we still refer to the wiki as our working area (and it’s the only place - I think - we have the info about the bi-weekly calls, which is now outdated!) https://wiki.spdx.org/view/Legal_Team
>
> While I have no appetite to shut down the wiki and there are some good resources there, what are thoughts about perhaps redefining how we use it? Off top of head:
> - for meeting minutes
> - recording old decisions (existing, but this could mean we could still opt to record stuff there in the future if it’s deemed the best place?)
> - proposals we are hashing out, but aren’t appropriate for a Github issue
>
> In the spirit of having only one place to update - I’m thinking we might move the call info to the Github readme and remove from the wiki page?? more likely to be seen there.
>
> Thoughts? ideas??
>
> Thanks,
> Jilayne
>
>
>
>
>
>
>