Changing public reception of Premake

[Lusito]

I guess it's painfully obvious, but that's more reason to start changing something.
Premake does not present itself very well to the world.
Googling premake brings me to (In order):

• The github page
• The sourceforge page
• industrious one page
• bitbucket page

That is 4 different pages!

It's good that github is the first entry, since it's the latest one, but why are the other ones still active ?

• Sourceforge shows content from version 3.7 and that version 4.0 is released, but the old documentation remains.
• Bitbucket shows that content has moved to gibhub, but:
  • It's not highlighted red or anything.. anyone used to skipping headers and introductions will not read it.
  • There is still documentation about premake5.

Googling Premake5 will bring you to bitbucket first!
I think that the old places are still up & running is the reason why google lists them as high as they are right now.

Almost all discussion entries about premake show something like "not updated since 2010".
This is probably another symptom of the above.

Looking at the main page (Github), it shows 5.0 alpha and 4.4 beta. People don't like alpha or beta. They like stable releases. 5.0 has been alpha since at least 2013.

My suggestions:

• Remove all content from the old pages, replace it with a link to the new page. This should help prevent search engines from indexing old pages as high as currently.
• If possible, add an automatic redirect to the new page.
• Remove the forum from http://industriousone.com/forums/premake. The content there is so old there is probably no use for keeping it.
• If the google group is the currently active forum, then by all means put a link to it on the github page and readme.md.
• Put a link to the github wiki into the readme.md on github. Few projects use the wiki on github, so if you don't point people to it, they won't try to look for it.
• Add a short & nice description of the project into the readme.md.
• And most of all, cut features as much as needed to get 5.0 golden.
  • Don't make this into Duke Nukem Forever.

A nice example of a helpful readme.md is Ashley:

• Appealing logo
• Short but informative description
• Every link you need to get started using it
• Information about the community and how to contribute

I really like premake, but it saddens me to see it not using its full potential.

[starkos]

That sounds like a great plan. Let me know if I can do anything to help!

[Lusito]

Well, since you are the owner, I guess only you have access to the old pages.. As far as the github stuff goes everyone could help out, but removing the old stuff would be up to you.

I could do some work on the readme.md and the homepage and create prs.
But since I'm not very deep into the core development I have no idea of the roadmap. All I have done so far is a netbeans generator.
So it'd probably be best if someone actually working on the core could put together a roadmap of things that are most important for 5.0 and then we could try to assign the tasks.

[starkos]

If you have a SourceForge ID I can give you access to the web hosting there. Same with BitBucket. I'm not sure how to do a redirect on BB, but the SF pages should be easy enough to replace.

We definitely will want to redirect and not just drop the pages (otherwise I'd just do it myself) since there are lot of links floating around.

Ideally I'd also love to see the tickets in the BitBucket issue tracker migrated. @TurkeyMan took that on last time around; I don't blame him for not wanting to do it again.

I will see about adding the Premake content to a norobots.txt on Industrious One to get it out of the index.

And most of all, cut features as much as needed to get 5.0 golden

I hear you, but that's not entirely up to me. We're not close enough to release to branch yet, and we don't have a proper community manager to nudge people toward fixing bugs instead of creating new features. Kind of have to make the best of what the community wants to contribute. I am actively working toward the 5.0 release as much as my time permits though, FWIW.

[Lusito]

If you have a SourceForge ID .. Same with BitBucket.

I had accounts years ago, I'll see if I still have access to them.

I'm not sure how to do a redirect on BB

Bitbucket seems to support a redirect if you delete a repository:
https://confluence.atlassian.com/display/BITBUCKET/Delete+a+repository

Ideally I'd also love to see the tickets in the BitBucket issue tracker migrated.

I'd only migrate the latest ones (2015).. A good rule in software development is: If a ticket has not been touched for over a year, it's probably not that important and can be closed. And if it is important, it will pop up again sooner or later.
There are 183! Tickets open on Bitbucket. Working through them alone will use up so much time that would be better spend on working on 5.0.

Is there an actual roadmap for 5.0 ?
I don't consider this wiki entry an actual roadmap.
A roadmap should contain a list of features and bugfixes that are a major part of the release.

[Lusito]

Bitbucket: Lusito
Sourceforge: ttk-bandit

[Lusito]

Are you set on the Confluence decision ?
I think github wiki is good for small API documentation and/or tutorials, but any API that is a bit bigger is really hard to navigate in github wiki.
I have previously worked with confluence and found it very easy to navigate as well as write technical documentation (plus it's free for open source projects).
Even if Confluence is out of the question, please consider something else than github wiki.

Github issue tracking should suffice, tho someone should probably add some milestones and (more) labels.

[TurkeyMan]

@Lusito Are you suggesting you're not happy with the state of the docs? Can you give some specifics?
I kinda like them.

[Lusito]

I'm saying navigating this wiki is difficult, especially for newcomers. It takes a lot of time to find the parts you are actually looking for.
A lot of the pages are only linked to in subpages. Once you are in a page, all navigation info is gone.
Also, you have no idea where in the wiki structure you currently are.

For example:
https://github.com/premake/premake-core/wiki/basedir
If I got to this page from google I ask myself the following questions:

• What page does this command belong to ?
• Where can I find other commands of the same scope?
• Where can I find more basic tutorials ?

It would already help a little to have a sidebar with the content of the current "Home" page and possibly a link "back" to the parent page.
But that's not an ideal solution either. Markdown is not suitable for technical documentation of this size in my opinion.

[starkos]

I'll reply in more detail later, but it looks like we can at least add a sidebar TOC to improve navigation.

[Lusito]

There should be a button "add sidebar".. I'm guessing only the owner or contributors can see it.

[starkos]

Are you sure? I think you can just add a file named _sidebar.md? See https://github.com/gollum/gollum/wiki

[Lusito]

both works. I guess it depends how you'd rather edit your wiki

[starkos]

I think using _sidebar.md is the way to go, that way we can all maintain it.

[Lusito]

The button creates the file. There is no difference in the result..
I personally like to edit it online, since it allows a preview. But editing it online will create git commits. So there is literally no difference.

[starkos]

Editing online is no problem, you are correct that there is no difference.

[ghost]

I will see about adding the Premake content to a norobots.txt on Industrious One to get it out of the index.

This doesn't sound like a very good idea. It might hurt your search engine ranking.

I would suggest setting up a HTTP 301 Moved Permanently redirect for each page. If you're running on Apache, this might be easiest to do with a .htaccess file. I think that the syntax supports regex. There's a pretty good example here.

[starkos]

I would suggest setting up a HTTP 301 Moved Permanently redirect for each page.

I am primarily concerned with keeping the forum topics up, since there are still incoming links. There is no new location for these. Your point is well-taken though and I will try to redirect pages where I can.

[starkos]

Sorry for the delay…you now have access to project on SF.net.

I would still rather not delete the Bitbucket repos until we've had a chance to close of migrate at least the most recent issues.

Comments welcome.

[Lusito]

Sourceforge has been flattened

[starkos]

Nice, thanks! Do you need anything else from me?

[ghost]

Where'd this get up to?

[starkos]

SourceForge was shut down, and some improvements made to the documentation. Some of the tasks mentioned are on me (adding norobots.txt to industriousone.com), others can be done by anyone (adding a sidebar TOC to GitHub wiki).

[Croydon]

I don't want to sound rude, but taking the chance that I will...

Please ask yourself from an outsider perspective: Why should I trust a tool which doesn't trust itself enough since 2010 to make a stable release?

Are all releases since 2010 that unstable?
If yes, what's going wrong?
If these are pretty stable release, why not call them stable?

[starkos]

Because...

• the Xcode and Gmake exporters both need lots of work, and…
• if I say that its final, people will expect the APIs to not change, and we're not at a place where they can be locked down, and…
• despite what people seem to think I should think, I'm not actually concerned with what other people think; I do the best I can with the little time I have

If you're volunteering to help, we'd love to have you!